<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html><head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>Formatted String Printing Functions</title>
<style type="text/css">
body {
    margin: auto;
    font-family: Verdana, sans-serif;
    padding: 8px 1%;
}

a { color: #044a64 }
a:visited { color: #734559 }

.logo { position:absolute; margin:3px; }
.tagline {
  float:right;
  text-align:right;
  font-style:italic;
  width:300px;
  margin:12px;
  margin-top:58px;
}

.toolbar {
  text-align: center;
  line-height: 1.6em;
  margin: 0;
  padding: 0px 8px;
}
.toolbar a { color: white; text-decoration: none; padding: 6px 12px; }
.toolbar a:visited { color: white; }
.toolbar a:hover { color: #044a64; background: white; }

.content    { margin: 5%; }
.content dt { font-weight:bold; }
.content dd { margin-bottom: 25px; margin-left:20%; }
.content ul { padding:0px; padding-left: 15px; margin:0px; }

/* rounded corners */
.se  { background: url(../images/se.gif) 100% 100% no-repeat #044a64}
.sw  { background: url(../images/sw.gif) 0% 100% no-repeat }
.ne  { background: url(../images/ne.gif) 100% 0% no-repeat }
.nw  { background: url(../images/nw.gif) 0% 0% no-repeat }

/* Things for "fancyformat" documents start here. */
.fancy img+p {font-style:italic}
.fancy .codeblock i { color: darkblue; }
.fancy h1,.fancy h2,.fancy h3,.fancy h4 {font-weight:normal;color:#044a64}
.fancy h2 { margin-left: 10px }
.fancy h3 { margin-left: 20px }
.fancy h4 { margin-left: 30px }
.fancy th {white-space:nowrap;text-align:left;border-bottom:solid 1px #444}
.fancy th, .fancy td {padding: 0.2em 1ex; vertical-align:top}
.fancy #toc a        { color: darkblue ; text-decoration: none }
.fancy .todo         { color: #AA3333 ; font-style : italic }
.fancy .todo:before  { content: 'TODO:' }
.fancy p.todo        { border: solid #AA3333 1px; padding: 1ex }
.fancy img { display:block; }
.fancy :link:hover, .fancy :visited:hover { background: wheat }
.fancy p,.fancy ul,.fancy ol { margin: 1em 5ex }
.fancy li p { margin: 1em 0 }
/* End of "fancyformat" specific rules. */

</style>
  
</head>
<body>
<div><!-- container div to satisfy validator -->

<a href="../index.html">
<img class="logo" src="../images/sqlite370_banner.gif" alt="SQLite Logo"
 border="0"></a>
<div><!-- IE hack to prevent disappearing logo--></div>
<div class="tagline">Small. Fast. Reliable.<br>Choose any three.</div>

<table width=100% style="clear:both"><tr><td>
  <div class="se"><div class="sw"><div class="ne"><div class="nw">
  <table width=100% style="padding:0;margin:0;cell-spacing:0"><tr>
  <td width=100%>
  <div class="toolbar">
    <a href="../about.html">About</a>
    <a href="../sitemap.html">Sitemap</a>
    <a href="../docs.html">Documentation</a>
    <a href="../download.html">Download</a>
    <a href="../copyright.html">License</a>
    <a href="../news.html">News</a>
    <a href="../support.html">Support</a>
  </div>
<script>
  gMsg = "Search SQLite Docs..."
  function entersearch() {
    var q = document.getElementById("q");
    if( q.value == gMsg ) { q.value = "" }
    q.style.color = "black"
    q.style.fontStyle = "normal"
  }
  function leavesearch() {
    var q = document.getElementById("q");
    if( q.value == "" ) { 
      q.value = gMsg
      q.style.color = "#044a64"
      q.style.fontStyle = "italic"
    }
  }
</script>
<td>
    <div style="padding:0 1em 0px 0;white-space:nowrap">
    <form name=f method="GET" action="http://www.sqlite.org/search">
      <input id=q name=q type=text
       onfocus="entersearch()" onblur="leavesearch()" style="width:24ex;padding:1px 1ex; border:solid white 1px; font-size:0.9em ; font-style:italic;color:#044a64;" value="Search SQLite Docs...">
      <input type=submit value="Go" style="border:solid white 1px;background-color:#044a64;color:white;font-size:0.9em;padding:0 1ex">
    </form>
    </div>
  </table>
</div></div></div></div>
</td></tr></table>
<div class=startsearch></div>
  
<a href="intro.html"><h2>SQLite C Interface</h2></a><h2>Formatted String Printing Functions</h2><blockquote><pre>char *sqlite3_mprintf(const char*,...);
char *sqlite3_vmprintf(const char*, va_list);
char *sqlite3_snprintf(int,char*,const char*, ...);
char *sqlite3_vsnprintf(int,char*,const char*, va_list);
</pre></blockquote><p>
These routines are work-alikes of the "printf()" family of functions
from the standard C library.</p>

<p>The sqlite3_mprintf() and sqlite3_vmprintf() routines write their
results into memory obtained from <a href="../c3ref/free.html">sqlite3_malloc()</a>.
The strings returned by these two routines should be
released by <a href="../c3ref/free.html">sqlite3_free()</a>.  Both routines return a
NULL pointer if <a href="../c3ref/free.html">sqlite3_malloc()</a> is unable to allocate enough
memory to hold the resulting string.</p>

<p>The sqlite3_snprintf() routine is similar to "snprintf()" from
the standard C library.  The result is written into the
buffer supplied as the second parameter whose size is given by
the first parameter. Note that the order of the
first two parameters is reversed from snprintf().  This is an
historical accident that cannot be fixed without breaking
backwards compatibility.  Note also that sqlite3_snprintf()
returns a pointer to its buffer instead of the number of
characters actually written into the buffer.  We admit that
the number of characters written would be a more useful return
value but we cannot change the implementation of sqlite3_snprintf()
now without breaking compatibility.</p>

<p>As long as the buffer size is greater than zero, sqlite3_snprintf()
guarantees that the buffer is always zero-terminated.  The first
parameter "n" is the total size of the buffer, including space for
the zero terminator.  So the longest string that can be completely
written will be n-1 characters.</p>

<p>The sqlite3_vsnprintf() routine is a varargs version of sqlite3_snprintf().</p>

<p>These routines all implement some additional formatting
options that are useful for constructing SQL statements.
All of the usual printf() formatting options apply.  In addition, there
is are "%q", "%Q", and "%z" options.</p>

<p>The %q option works like %s in that it substitutes a nul-terminated
string from the argument list.  But %q also doubles every '\'' character.
%q is designed for use inside a string literal.  By doubling each '\''
character it escapes that character and allows it to be inserted into
the string.</p>

<p>For example, assume the string variable zText contains text as follows:</p>

<p><blockquote><pre>
char *zText = "It's a happy day!";
</pre></blockquote></p>

<p>One can use this text in an SQL statement as follows:</p>

<p><blockquote><pre>
char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES('%q')", zText);
sqlite3_exec(db, zSQL, 0, 0, 0);
sqlite3_free(zSQL);
</pre></blockquote></p>

<p>Because the %q format string is used, the '\'' character in zText
is escaped and the SQL generated is as follows:</p>

<p><blockquote><pre>
INSERT INTO table1 VALUES('It''s a happy day!')
</pre></blockquote></p>

<p>This is correct.  Had we used %s instead of %q, the generated SQL
would have looked like this:</p>

<p><blockquote><pre>
INSERT INTO table1 VALUES('It's a happy day!');
</pre></blockquote></p>

<p>This second example is an SQL syntax error.  As a general rule you should
always use %q instead of %s when inserting text into a string literal.</p>

<p>The %Q option works like %q except it also adds single quotes around
the outside of the total string.  Additionally, if the parameter in the
argument list is a NULL pointer, %Q substitutes the text "NULL" (without
single quotes).  So, for example, one could say:</p>

<p><blockquote><pre>
char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES(%Q)", zText);
sqlite3_exec(db, zSQL, 0, 0, 0);
sqlite3_free(zSQL);
</pre></blockquote></p>

<p>The code above will render a correct SQL statement in the zSQL
variable even if the zText variable is a NULL pointer.</p>

<p>The "%z" formatting option works like "%s" but with the
addition that after the string has been read and copied into
the result, <a href="../c3ref/free.html">sqlite3_free()</a> is called on the input string.
</p><p>See also lists of
  <a href="objlist.html">Objects</a>,
  <a href="constlist.html">Constants</a>, and
  <a href="funclist.html">Functions</a>.</p>
